# cd <install-dir>/bin # ./rhq-server.sh console
The RHQ Server is actually a customized JBossAS server typically located in the jbossas directory where the RHQ Server distribution is installed. When you start the RHQ Server, you are actually starting a JBossAS server instance.
Running in Debug Mode
Sometimes you need the server launcher scripts (i.e. rhq-server.[sh,bat]) to emit debug messages. To run the scripts in debug mode, define the environment variable RHQ_SERVER_DEBUG to 'true'. To disable this debug mode, unset that environment variable, or set it to 'false'.
To run the RHQ Server itself in debug mode, you can set "rhq.server.log-level" to "DEBUG" in <install-dir>/bin/rhq-server.properties. You would do this if you need the RHQ Server itself to log debug messages. Note that the RHQ_SERVER_DEBUG setting does not affect whether or not the RHQ Server itself emits debug messages - that environment variable effects only the server launcher scripts.
We do not recommend modifying anything else under the JBossAS directory (e.g. jbossas) unless explicitly mentioned in the documentation; modifying any internal files could adversely affect the performance of the RHQ Server.
The RHQ Server can be run from within a console window or it can be installed as a Windows Service and run as a service.
The rhq-server.bat script is found in the <install-dir>/bin directory of the distribution. To run the RHQ Server in a console, execute the command rhq-server.bat console. Alternatively, open Windows Explorer and locate the <install-dir>/bin/rhq-server-console.bat file. Double click on the file to start the RHQ Server.
The rhq-server.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the RHQ Server at a new JVM. The comments at the top of the rhq-server.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the RHQ Server to run; sensible defaults are used.
Starting with Windows Vista use a command window started with the "Run as Administrator" option. This is required when manipulating Windows services.
When the RHQ Server runs as a Windows service, it runs as a particular user. This user is specified by the RHQ_SERVER_RUN_AS environment variable. The RHQ_SERVER_RUN_AS_ME variable overrides the RHQ_SERVER_RUN_AS variable and allows the RHQ Server to run as the current user. If neither of these two variables are set, the RHQ Server Windows Service runs as the System account. Both variables are explicitly mentioned here because of their security implications. All environment variables can be defined in the rhq-server.bat script. To run the RHQ Server Windows service as a specific user, define the RHQ_SERVER_RUN_AS variable with a value conforming to the strict Microsoft Windows format of: DOMAIN\username, for example, MYDOMAIN\john. Alternatively, define the RHQ_SERVER_RUN_AS_ME variable - no value is required; the RHQ Server runs as the username defined in the USERNAME environment variable. Execute the rhq-server.bat script with one of the following command line options:
install - This installs the RHQ Server as a Windows service. At the prompt, enter the password of the user designated to run the server. The Windows service now starts the server during the system boot. You can change this behavior by modifying the wrapper configuration file described below.
start - This starts the Windows service, effectively starting the RHQ Server. Ensure that you have run the rhq-install.bat install command first. Alternatively, start the RHQ Server by using the Windows Services Administrative Tool.
stop - This stops the Windows Service, effectively stopping the RHQ Server. You must have installed and started the Windows Service first in order to stop it. Alternatively, stop the RHQ Server by using the Windows Services Administrative Tool instead.
remove - This removes the Windows Service from your Windows operating system. If the service is running, it is first stopped. Once the service is removed, it is no longer started at boot time and you can no longer start it with the start option.
status - If the service is installed, this option informs you if the server is currently running or not.
The RHQ Server Windows Service can also be modified by the service wrapper configuration file, located at <install-dir>\bin\wrapper\rhq-server-wrapper.conf. This file sets some of the Java Service Wrapper configuration settings. The rhq-server.bat script uses the Java Service Wrapper utility to install and control the Windows Service. Before editing this file, refer to the Java Service Wrapper's property configuration documentation located at http://wrapper.tanukisoftware.org/doc/english/properties.html. A few common settings you might be interested in modifying are:
wrapper.app.parameter.# - these command line options are passed to the RHQ Server. Because the RHQ Server runs inside a JBossAS container, the options are passed on to this container. Each individual option and its value must be given its own wrapper configuration property, and must be placed in numerical order. Do not change any of the five default properties, wrapper.app.parameter.1 thru .5; to add a new property, start with wrapper.app.parameter.6. You should not need to add or modify these properties for a standard configuration.
wrapper.java.additional.# - these additional VM options are passed directly to the VM (such as -Xmx or -D). As with the wrapper.app.parameter.# properties, you must increment each option in numerical order. Do not edit the existing wrapper.java.additional.# properties unless, for example, you want to adjust the memory requirements of the RHQ Server or you want to point to your own log configuration file. You can add, remove, and modify other properties. For example: wrapper.java.additional.12=-XX:+DisableExplicitGC
wrapper.ntservice.starttype - by default, this is set to AUTO_START. This starts the RHQ Server automatically at boot time. To manually start the service, change the value to DEMAND_START.
There are many other Java Service Wrapper configuration properties you can set. If you are interested in learning more, refer to the Java Service Wrapper documentation at http://wrapper.tanukisoftware.org/doc/english/properties.html. Also refer to the comments located in the rhq-server-wrapper.conf file. You can also configure the RHQ Server Windows Service by creating a <install-dir>\bin\wrapper\rhq-server-wrapper.inc include file. This effectively augments the service wrapper configuration file, <install-dir>\bin\wrapper\rhq-server-wrapper.conf. If you want to add additional Java VM options, we recommend that you add your settings in here, as opposed to the rhq-server-wrapper.conf file.
The RHQ Server can run from a console window or run as a service started by the init process.
The rhq-server.sh file, located in the <install-dir>/bin directory, contains a detailed list of the environment variables it requires to run. For most variables, sensible defaults are used and therefore do not need tweaking.
You can specify the path to the Java installation you want to use to run the RHQ Server. Before starting the RHQ Server, you can edit the rhq-server.sh file and ensure that either the RHQ_SERVER_JAVA_HOME or the RHQ_SERVER_JAVA_EXE_FILE_PATH variable is set appropriately.
To run the RHQ Server in a console, execute the following commands as the root user:
# cd <install-dir>/bin # ./rhq-server.sh console
To ensure the RHQ Server is started at boot time, the rhq-server.sh script can be managed by the init process. The script must be copied to the appropriate location and the RHQ_SERVER_HOME variable must be set to the installation directory of the RHQ Server. The exact procedure on how to do this varies between different flavors of UNIX. The example procedure below describes this process on Red Hat Enterprise Linux 5.2.
Unlike the Windows script, this UNIX script does not utilize the Java Service Wrapper utility.
The rhq-server.sh script can be placed under the /etc/init.d directory and managed by the service and chkconfig command. To run the RHQ Server as a service on Red Hat Enterprise Linux 5.2 and ensure that it starts in run level 5, follow the procedure below as the root user:
Copy the rhq-server.sh script into the /etc/init.d directory.
cp <install-dir>/bin/rhq-server.sh /etc/init.d
Edit the /etc/init.d/rhq-server.sh script and set the RHQ_SERVER_HOME variable to the RHQ Server install directory. For example:
RHQ_SERVER_HOME=/opt/rhq-server-4.6.0
Edit the /etc/init.d/rhq-server.sh script and add the following lines to the top of the file, directly under #!/bin/sh. The last two parameters in the #chkconfig: 2345 95 20 line specify the start and stop priority respectively; edit these accordingly.
#!/bin/sh #chkconfig: 2345 95 20 #description: RHQ Server #processname: run.sh
Add the service to the chkconfig service management command.
# chkconfig --add rhq-server.sh # chkconfig rhq-server.sh --list
Ensure the service will start in run level 5.
# chkconfig --level 5 rhq-server.sh on
The RHQ Server service can now be managed by the command:
service rhq-server.sh { start | stop | status }
For example, to start the service, enter the following command:
# service rhq-server.sh start
After the server is started, the console can be accessed by default at http://localhost:7080 with the default user/password of rhqadmin/rhqadmin. The Initial auto discovery and import page gives more details.